<!--slrpintr.htm-->
<HTML><HEAD>
<!--<BASE HREF="http://members.bellatlantic.net/~sweyer/newton/sloup/slrpintr.htm">-->
<TITLE>Sloup: Introduction/Interface</TITLE>
<META NAME="ISBN" CONTENT="slrpintr.htm">
<META NAME="SHORTTITLE" CONTENT="SloupIntro">
<META NAME="AUTHOR" CONTENT="Steve Weyer">
<META NAME="COPYRIGHT" CONTENT="&copy; 1993-98, S. Weyer">
<META NAME="_package.labels" CONTENT="'Books">
<META NAME="_package.compressed" CONTENT="true">
<META NAME="data.clickAddFile" CONTENT="func(x,y,href,obj)
begin
	PlaySound(@51); /*ROM_click*/
	GetRoot().|Sloup:TKnollSys|:?addFile(
		&quot;text/html&quot;, href, obj.item.data, nil);
end
">
<META NAME="data.notes1.slp" CONTENT="clickAddFile">
</HEAD><BODY>

<H1><A NAME="What is Sloup?">What is Sloup?</A></H1>

<P>Sloup is a utility for transferring data or text between desktop files
and Newton "soups" (object-oriented databases).

<P>Feature summary:
<UL>
<LI>transfer desktop text to/from Notes (and Outlines and Checklists on NOS 2.x)
<LI>import/export Names (examples provided)
<LI>import/export tab-delimited data via your desktop terminal emulator (or NTK Inspector or TCP)
<LI>use your desktop keyboard to enter text on your Newton
<LI>print data, values and errors to a desktop "inspector" window
<LI>transfer source and graphics for applications in Newt Development
Environment and books in Newt's Cape
</UL>

<P><STRONG>Warning: since Sloup can add or remove entries from your Newton
soups, please keep your information backed up regularly, and follow the
formats and commands carefully.</STRONG>

<P>For the latest information and versions, please check
<A HREF="../index.htm">Steve's releases page.</A>

<H2>Why Sloup?</H2>

<P>I wanted a convenient way to move information from the desktop to soups
on the Newton, especially text paragraphs to separate Notepad entries, and
vice versa. Desktop synchronization/transfer tools were not always available
for different versions of Newton OS and different desktop systems, and did
not always provide the current set of features I wanted. See <A
HREF="../toolinfo.htm">related tools</A>. Apple provided several Newton
programming examples (Slurp, SuperSlurp) for soup transfer, which I modified
over time, adding many improvements.

<P>Although Sloup was created primarily to support moving NewtonScript
application/method sources and graphic/sound resources by users of the
<A HREF="../newtdev.htm">Newt Development Environment</A>, and HTML source and
graphics for <A HREF="../newtscape.htm">Newt's Cape</A> books, I thought
that this may be useful as a general utility for others to transfer Notes,
Names and other data. Sloup can transfer binary data -- graphics (including
gray scale on NOS 2.1), sounds (and packages on NOS 2.x) -- via a simple
encoding format.

<P>To assist in real-time application development with Newt, I added some
"Inspector-like" functionality so that you can use your desktop keyboard to
type into Newton fields, and to redirect Print and Notify results to a
window on your desktop.

<H2>Distribution</H2>

<P>Sloup is shareware ($10). Sloup may be freely distributed via online
services and bulletin boards if it is unmodified and includes this and other
files mentioned here. It may not be commercially bundled or redistributed on
CD-ROM, floppy disk, PCMCIA, networks or other media without permission.

<P>Sloup is currently free to registered users of
<A HREF="../newtdev.htm">Newt Development Environment</A> and
<A HREF="../newtscape.htm">Newt's Cape</A>.

<H1><A NAME="Setting up Sloup">Setting up Sloup</A></H1>

<P>Sloup makes no claims to being a user-friendly tool. The process of
configuring your terminal emulator and defining frame specifications may
yield strange errors. There are several <A
HREF="../toolinfo.htm">third-party tools</A> that provide alternatives, use
Sloup but hide some of this complexity. I can provide some documentation,
examples and interactive help (especially if you register), but you'll have
the most success if you have used terminal emulators, have a little
programming or database background, and are adventurous and not easily
frustrated.

<P>Once you've surpassed the initial configuration/setup hurdles, Sloup can
be quite useful for quickly and flexibly moving information in and out of
your Newton.

<P>Although the Sloup application has some controls and preferences, you
should think of it primarily as a "server". Once a connection has been
established, all of the commands come from the desktop client such as a
terminal emulator.

<P>For example, to send data to your Newton, you tell Sloup to Connect, and
then send text containing soup name, format specification, and data, via
your terminal emulator, usually as a text file. To send data from your
Newton, you also set Sloup to Connect; however, the text file that you send
contains a soup name and format specification, but no data -- just a Dump
command (this assumes you set up a log file to capture the data returned)

<P>When first getting started, it's usually a good idea to just give Sloup a
line at a time rather than sending it a large file. That way you can see the
status messages, and if there are errors, the desktop side may not hang.

<H2>Configuring Sloup and Desktop Communication</H2>

<P>Given the wide variety of terminal emulators that are available on Mac
(ZTerm, ClarisWorks,...), Windows (Terminal,...), Unix and other platforms,
I hope that these guidelines below are adequate, and that with a little
interpretation and experimentation, you will be running soon without excess
pain and suffering. Please send let me know which software you are using and
whether there was anything unusual you needed to do to get Sloup to work (or
if there's a comms package that did not work well or at all) -- I'll
summarize and make these accessible on the <A HREF="../sloup.htm">Sloup page</A>

<P>After installing the Sloup package, make sure you have a serial cable
still connected, no other desktop program using the serial port, and (on NOS
1.x) no other Newton application using communications: beaming, modem, etc.
If you are using a <A HREF="../toolinfo.htm">3rd-party front-end for Sloup</A>,
follow those directions; if you are using a desktop terminal
emulator, configure it initially as follows:

<UL>
<LI>Serial Tool (for file transfer, specify the Text Tool -- not XMODEM, or other protocols)
<LI>speed: 9600 baud (you can try 57600 or ADSP later in registered versions of Sloup)
<LI>8 data bits
<LI>1 stop bit
<LI>XON/XOFF software handshaking (on)
<LI>line wrap (turn it off)
<LI>local echo (up to you)
<LI>transmit delays between chars (0)
<LI>transmit delays between lines (0 -- unless XON/XOFF isn't supported)
<LI>translating tabs to spaces (no)
<LI>initiate/open connection
</UL>

<P>Start Sloup on the Newton, and choose connection speed (9600 is only
choice in public version) to match desktop configuration.

<P>Initiate/open desktop connection; tap Sloup's Connect button.

<P>To check that the connection is working, just type "xxx" on desktop-- you
should see a Sloup message: "not a soupname: xxx"

<P>Another simple thing to try before attempting anything more complicated
is to type (or click on the example in book version of this on Newton if
Sloup is installed):

<PRE><A HREF="notes1.slp">Notes
{}
hello there
BYE!</A>
</PRE>

<P>The note should appear in your Notepad (Unfiled folder)

<P>If things are working, send an example file. In Sloup, make sure it is
waiting for a soup name (if not, do Disconnect/Connect). On the desktop
side, "Send File..." or "Send Text..." in the comm program, and choose the
file to be sent, e.g., CasioNam.tab. Note: this is not a XMODEM, Kermit,
ZModem or other protocol, just text; alternatively, you could just Copy a
section from a text editor window and Paste it into your terminal emulator.
If you are doing a "Dump", immediately setup a file to log/receive/capture
the result.

<P>Sloup should display the number of entries received/dumped in a view near
the top of the screen. When the file transfer is complete, Sloup will
automatically wait for another transfer. I would suggest starting with the
CasioNam.tab example first (you could delete some of the lines, but don't
start making other modifications just yet...). Tap Disconnect to end the
connection, or just close Sloup.

<H1><A NAME="User Interface: Sloup">User Interface: Sloup</A></H1>

<DL>
<DT>drag dot[top center]
<DD>main view can be moved

<DT><A NAME="Inspect?">Inspect?</A>[checkbox; top left]

<DD>default off. toggles to a smaller view (see "Inspector"). input
characters/lines are directed to current "key view" rather than to a soup.
saved as a Preference

<DT><A NAME="Paste">Paste</A>[button; top left]
<DD>pastes current text entry (key view) or highlighted selection over current connection

<DT><A NAME="Connected_Disconnected">Connected/Disconnected</A>[status text; below Paste]
<DD>depending on state of connection

<DT><A NAME="9600 (speed)">9600 (speed)</A>[picker; top right]
<DD>the standard, public release just offers 9600(serial); other versions of
Sloup offer: 19200, 38400, 57600, ADSP. (If you are using ADSP connection in
Sloup with ClarisWorks, choose the AppleTalk ADSP Tool, leave your zone as
"*", and set your Local Name; select "Wait for Connection"; on Newton, a
"NetChooser" dialog appears -- select name of desktop system)

<DT><A NAME="Connect_Disconnect">Connect/Disconnect</A>[button; top right]
<DD>open or close a connection using the current connection speed, e.g., 9600

<DT><A NAME="$ (Register)">"$" (Register)</A>[button; top right]
<DD>If the Newton Register application is installed, tap on the "$" icon to
open up a registration screen. This is a convenient and reasonably safe way
to register with a credit card via Newton email (e.g., Aloha). <A
HREF="../index.htm#Register">web, Newton, Mac, Windows versions of
Register</A>

<DT><A NAME="i (info)">"i" (info)</A>[button; top right]
<DD>displays About box (URLs are active if Newt's Cape is installed)

<DT><A NAME="Newt icon">Newt icon</A>[icon; center]
<DD>If <A HREF="../newtdev.htm">Newt Development Environment</A>
is installed, tap on Newt's icon to start it. Typically, you might start
Newt, then tap on Inspect? Or, you can start Newt first, and select Sloup
from the overview menu

<DT><A NAME="Status:">Status:</A>[text; center]
<DD>displays current state of connection

<DT><A NAME="Soup:">Soup:</A>[text; center]
<DD>name of current soup, e.g., Notes

<DT><A NAME="Entries:">Entries:</A>[text; center]
<DD>displays number of entries imported/exported

<DT><A NAME="Idxs:">Idxs:</A>[text; center]
<DD>number of indexes for current soup

<DT><A NAME="Entry:">Entry:</A>[text; bottom center]
<DD>current line (or recent if Refresh? is off or at higher connect speeds)

<DT><A NAME="AutoConn?">AutoConn?</A>[checkbox; bottom left]
<DD>default: off. if checked, connects immediately and automatically upon
Sloup startup using last settings, e.g., serial (speed), ADSP (zone, host)

<DT><A NAME="Sound">Sound</A>[picker; bottom center]
<DD>default: none. pick a built-in sound to play when connecting and at end
of transaction; saved as a Preference across sessions/reboots

<DT><A NAME="Refresh?">Refresh?</A>[bottom right]
<DD>default: on. turn off to speed up transfers -- Sloup only refreshes when
there is extra time available; this might mean every line at 9600, only
every few lines at higher speeds. Leaving it on does a refresh after each
line. saved as a Preference
</DL>


<H1><A NAME="Terminology: Sloup">Terminology: Sloup</A></H1>

<DL>
<DT><A NAME="soup">soup</A>
<DD>an object-oriented database. Its entries are frames

<DT><A NAME="frame">frame</A>
<DD>a frame is a Newton object which contains slots and values. It's similar
to a database record, or row of a relational table. Also called an entry.
Although the frames in a soup can have different slots, it is more efficient
for the system (and easier to write applications) if the frames are similar,
if not identical, in structure

<DT><A NAME="slot">slot</A>
<DD>a slot is basically a field or attribute that contains a value. A slot could have different types of values, though not if you want to index a slot

<DT>value
<DD>a value can be a literal value (number, string, symbol, boolean) or an array, frame or binary object

<DT><A NAME="index">index</A>
<DD>if an index is specified for a slot, the Newton can uses value as a key to access an entry or sort entries faster. This assumes that all of values of a slot are of the same type (integer, symbol or string)

<DT><A NAME="entry specification">entry specification</A>
<DD>an entry specification is a frame that describes the order of fields and types of values
</DL>

<HR>

<P>Version 2.1. Last updated: Jan 1998

<UL>
<LI><A HREF="#What is Sloup?">Top</A>
<LI>Next: <A HREF="slrpfmts.htm">Sloup File Formats</A>
<LI><A HREF="slrptoc.htm">Table of Contents</A>
<LI>Index: <A HREF="slrpindx.htm#A">A</A> | <A HREF="slrpindx.htm#B">B</A> | <A HREF="slrpindx.htm#C">C</A> | <A HREF="slrpindx.htm#D">D</A> | <A HREF="slrpindx.htm#E">E</A> | <A HREF="slrpindx.htm#F">F</A> | <A HREF="slrpindx.htm#G">G</A> | <A HREF="slrpindx.htm#H">H</A> | <A HREF="slrpindx.htm#I">I</A> | <A HREF="slrpindx.htm#J">J</A> | <A HREF="slrpindx.htm#K">K</A> | <A HREF="slrpindx.htm#L">L</A> | <A HREF="slrpindx.htm#M">M</A> | <A HREF="slrpindx.htm#N">N</A> | <A HREF="slrpindx.htm#O">O</A> | <A HREF="slrpindx.htm#P">P</A> | <A HREF="slrpindx.htm#Q">Q</A> | <A HREF="slrpindx.htm#R">R</A> | <A HREF="slrpindx.htm#S">S</A> | <A HREF="slrpindx.htm#T">T</A> | <A HREF="slrpindx.htm#U">U</A> | <A HREF="slrpindx.htm#V">V</A> | <A HREF="slrpindx.htm#W">W</A> | <A HREF="slrpindx.htm#X">X</A> | <A HREF="slrpindx.htm#Y">Y</A> | <A HREF="slrpindx.htm#Z">Z</A>
<LI><A HREF="mailto:weyer@kagi.com">weyer@kagi.com</A>
<LI><A HREF="../index.htm">Steve's releases page</A>
</UL>

</BODY></HTML>
